package cn.song.freight.service;

import cn.song.freight.domain.dto.BatchDeleteStrategyAssignmentDTO;
import cn.song.freight.domain.dto.BatchStrategyAssignmentDTO;
import cn.song.freight.domain.dto.StrategyAssignmentDTO;
import cn.song.freight.domain.entity.StrategyAssignmentDO;
import cn.song.freight.domain.query.StrategyAssignmentQuery;
import cn.song.freight.domain.result.R;
import com.baomidou.mybatisplus.extension.service.IService;

import java.util.List;
/**
 * 运费策略分配服务接口
 * <pre>
 * 该服务实现提供物流系统的运费策略分配管理功能，支持单个和批量分配关系的增删改查操作，
 * 并提供基于多种条件的分配关系查询功能，用于维护系统中仓库、物流公司与运费策略的关联配置。
 *
 * 核心功能：
 * - 运费策略分配关系的添加、删除、更新和查询
 * - 支持单个和批量分配关系操作
 * - 数据完整性校验和业务规则验证
 * - 分配关系的状态管理和使用情况检查
 *
 * 分配关系说明：
 * 一个仓库与一个物流公司的组合可以分配一个运费策略，用于计算该组合下的运费
 *
 * @author SongRenShuo
 * @version 3.0.0
 * @since 2025-08-23
 */
public interface StrategyAssignmentService extends IService<StrategyAssignmentDO> {
    /**
     * 分配运费策略
     * <pre>
     * 该方法实现运费策略的分配功能，会先校验传入的仓库编码和物流公司编码组合是否已存在，
     * 避免重复分配，确保数据的唯一性和一致性，并记录操作时间和操作人信息。
     *
     * @param strategyAssignmentDTO 运费策略分配数据传输对象，包含仓库编码、物流公司编码和策略ID等信息
     * @return 分配结果，true表示分配成功，false表示分配失败
     */
    R<Boolean> assignStrategy(StrategyAssignmentDTO strategyAssignmentDTO);

    /**
     * 批量分配运费策略
     * <pre>
     * 该方法实现运费策略的批量分配功能，会对传入的仓库编码和物流公司编码进行笛卡尔积组合，
     * 逐一校验组合是否已存在，避免重复分配，并记录操作时间和操作人信息，提高分配效率。
     *
     * @param batchDTO 批量运费策略分配数据传输对象，包含仓库编码列表、物流公司编码列表和策略ID等信息
     * @return 批量分配结果，包含成功分配的记录数
     */
        R<Integer> batchAssignStrategy(BatchStrategyAssignmentDTO batchDTO);

    /**
     * 删除运费策略分配
     * <pre>
     * 该方法实现运费策略分配的删除功能，会先校验分配关系是否存在，
     * 确保删除操作的安全性和准确性，避免误删不存在的数据，并记录操作日志便于追踪。
     *
     * @param strategyAssignmentId 要删除的运费策略分配ID
     * @return 删除结果，true表示删除成功，false表示删除失败
     */
    R<Boolean> deleteStrategyAssignment(Long strategyAssignmentId);

    /**
     * 批量删除运费策略分配
     * <pre>
     * 该方法实现运费策略分配的批量删除功能，会对传入的ID列表进行校验，
     * 确保要删除的记录存在，并记录操作日志便于追踪，提高删除效率并保证数据一致性。
     *
     * @param batchDeleteDTO 批量删除运费策略分配数据传输对象，包含要删除的ID列表
     * @return 批量删除结果，包含成功删除的记录数
     */
    R<Integer> batchDeleteStrategy(BatchDeleteStrategyAssignmentDTO batchDeleteDTO);

    /**
     * 查询运费策略分配列表
     * <pre>
     * 该方法实现运费策略分配的条件查询功能，支持按仓库编码、物流公司编码、策略ID和状态进行查询，
     * 查询结果包含符合条件的所有分配关系数据，便于查看和管理分配配置信息。
     *
     * @param query 运费策略分配查询对象，包含查询条件
     * @return 符合条件的运费策略分配列表
     */
    R<List<StrategyAssignmentDO>> getStrategyAssignments(StrategyAssignmentQuery query);

    /**
     * 更新运费策略分配状态
     * <pre>
     * 该方法实现运费策略分配状态的更新功能，会先校验分配关系是否存在，
     * 然后根据传入的状态值对分配关系进行状态更新操作，确保数据的实时性和准确性，并记录更新时间。
     *
     * @param strategyAssignmentId 要更新状态的运费策略分配ID
     * @param status 新的状态值
     * @return 更新结果，true表示更新成功，false表示更新失败
     */
    R<Boolean> updateStrategyAssignmentStatus(Long strategyAssignmentId, Integer status);
}
